Entity docs #171

IchHabeHunger54 · 2024-10-03T00:31:19Z

Adds some long-needed entity documentation. Supersedes #15 and #95 . Closes #90 . This PR:

Adds articles about the following:
- Entities in general
- Data and networking in the context of entities
- The LivingEntity, Mob and Player classes, along with their subclasses
- Attributes and AttributeModifiers
- Entity renderers and entity models
Removes the Entities article in the Networking section, in favor of the new Data and Networking article
Updates the Interaction Pipeline article with left-click and middle-click behavior, and also renames it to just Interactions
Adds an explanation for how block breaking speed is calculated, including how the various attributes affect this
- Also does some reformatting in the blocks article, while we're at it
Adds and adjusts links to the new Entities section as necessary
Adds a styleguide for Mermaid class diagrams to the Contributing doc
Explicitly leaves WIP markers for pathfinding, goals and brains, as well as animations, as these deserve their own PR(s)

Preview URL: https://pr-171.neoforged-docs-previews.pages.dev

Co-authored-by: Dennis C <[email protected]>

Co-authored-by: ChampionAsh5357 <[email protected]>

XFactHD

First pass over the changes, still have to do the 4 largest files.

docs/blocks/index.md

docs/entities/data.md

XFactHD · 2024-12-14T02:46:44Z

docs/entities/renderer.md

+    EntityRenderer-->ArrowRenderer;
+    EntityRenderer-->LivingEntityRenderer;


Suggested change

EntityRenderer-->ArrowRenderer;

EntityRenderer-->LivingEntityRenderer;

EntityRenderer-->LivingEntityRenderer;

EntityRenderer-->ArrowRenderer;

These should be switched around to avoid the arrow from LivingEntityRenderer to ArmorStandRenderer going through the ArrowRenderer node

Changing this makes the arrow go through the AbstractMinecartRenderer instead. I'm afraid there is no easy way of solving this.

docs/entities/renderer.md

docs/entities/data.md

docs/entities/index.md

docs/entities/data.md

ChampionAsh5357

Here's the requested feedback. Still a few WIP sections, so I'm wondering why it was brought out of draft early.

docs/blocks/index.md

ChampionAsh5357 · 2025-01-10T17:17:16Z

docs/concepts/events.md

@@ -120,6 +120,7 @@ graph TD;
    PlayerEvent-->CanPlayerSleepEvent;

    class Event,BlockEvent,EntityEvent,LivingEvent,PlayerEvent red;
+    class BlockDropsEvent,CanPlayerSleepEvent blue;


Is there a reason for this in an entity docs PR?

Mainly because this is the first PR that really makes use of Mermaid diagrams. I adopted the style guide of red -> abstract, blue -> non-abstract, and applied it to the only other diagram we had while I was at it.

docs/entities/attributes.md

docs/entities/livingentity.md

ChampionAsh5357 · 2025-01-10T18:38:56Z

docs/entities/livingentity.md

+Natural spawning is performed every tick for entities where `MobCategory#isFriendly()` is true, and every 400 ticks (\= 20 seconds) for entities where `MobCategory#isFriendly()` is false. If `MobCategory#isPersistent()` returns true, this process additionally also happens on chunk generation.
+
+For each chunk and mob category, it is checked whether there are less than `MobCategory#getMaxInstancesPerChunk() * loadedChunks / 289` in the world. Additionally, for each chunk, it is required that there are less than `MobCategory#getMaxInstancesPerChunk()` entities of that `MobCategory` near at least one player (near means that the distance between mob and player \<\= 128) for spawning of that `MobCategory` to occur.


It might be best to frame this with an example to get the actual numbers for each.

docs/entities/livingentity.md

docs/entities/renderer.md

neoforged-automation · 2025-01-10T22:33:47Z

@IchHabeHunger54, this pull request has conflicts, please resolve them for this PR to move forward.

# Conflicts: # docs/resources/client/models/bakedmodel.md # docs/resources/server/conditions.md

ChampionAsh5357

I give you...more comments!

ChampionAsh5357 · 2025-02-06T20:18:25Z

docs/blocks/index.md

+```java
+// This will return the tool's mining speed, or 1 if the held item is either empty, not a tool,
+// or not applicable for the block being broken.
+float destroySpeed = item.getDestroySpeed();


Technically, this takes in the BlockState to determine the destroy speed.

ChampionAsh5357 · 2025-02-06T20:20:01Z

docs/blocks/index.md

+if (player.hasEffect(MobEffects.DIG_SPEED))     { destroySpeed *= ...; }
+if (player.hasEffect(MobEffects.CONDUIT_POWER)) { destroySpeed *= ...; }


This is partially wrong. It applies the maximum amplifier from dig speed and conduit power before doing some math stuff.

ChampionAsh5357 · 2025-02-06T20:21:45Z

docs/entities/attributes.md

+| `nametag_distance` | `NAMETAG_DISTANCE` | `[0,32]`   | 32            | How far the nametag of the entity will be visible, in blocks.                                                                                        |
+| `swim_speed`       | `SWIM_SPEED`       | `[0,1024]` | 1             | A movement speed multiplier that is applied when the entity is underwater. This is applied independently from `minecraft:water_movement_efficiency`. |
+
+## Default Attributes


This section should also include the EntityAttributeModificationEvent for adding new attributes to existing entities.

ChampionAsh5357 · 2025-02-06T20:23:38Z

docs/entities/attributes.md

+And that's it! Just don't forget to register your `DeferredRegister` to the mod bus, and off you go.
+
+:::info
+We use `Holder<Attribute>` here, instead of `Supplier<RangedAttribute>` like with many other registered objects, as it makes working with entities a lot easier (most entity methods expect `Holder<Attribute>`s). If, for some reason, you need a `Supplier<RangedAttribute>` (or a supplier of any other subclass of `Attribute`), you should use `DeferredHolder<Attribute, RangedAttribute>` as the type.


Specify to use the explicit type you're using, since not everyone would use the RangedAttribute.

docs/entities/data.md

ChampionAsh5357 · 2025-02-06T21:13:24Z

docs/entities/renderer.md

+        if (renderer != null) {
+            // Add the layer to the renderer. Like above, construct a new MyRenderLayer.
+            // The EntityModelSet can be retrieved from the event through #getEntityModels.
+            renderer.addLayer(new MyRenderLayer(renderer, event.getEntityModels()));


This would not compile due to the generics.

ChampionAsh5357 · 2025-02-06T21:14:14Z

docs/entities/renderer.md

+        // Get the associated PlayerRenderer.
+        if (event.getSkin(skin) instanceof PlayerRenderer playerRenderer) {
+            // Add the layer to the renderer.
+            playerRenderer.addLayer(new MyRenderLayer(playerRenderer, event.getEntityModels()));


This would not compile due to the generics differing between the layer and the renderer.

ChampionAsh5357 · 2025-02-06T21:17:31Z

docs/entities/renderer.md

+
+## Animations
+
+NeoForge adds an optional system that allows entity animations to be defined in JSON files, similar to third-party libraries such as [GeckoLib][geckolib]. Animations are defined in JSON files located at `assets/<namespace>/neoforge/animations/entity/<path>.json` (so for the [resource location][rl] `examplemod:example`, the file would be located at `assets/examplemod/neoforge/animations/entity/example.json`). The format of an animation file is as follows:


This is technically not a complete NeoForge system. Animation definitions is a vanilla system for animations using keyframes and interpolation data. What NeoForge adds is the ability is to define these via JSON. That might be what this sentence is saying, but it's a bit confusing.

ChampionAsh5357 · 2025-02-06T21:21:50Z

docs/entities/renderer.md

+        {
+            // The name of the part to be animated.
+            // Must match the name of a part defined in your LayerDefinition (see above).
+            "bone": "head",


If there are multiple matches, it will just pick the first one it finds, which will always be a depth-first search iirc.

ChampionAsh5357 · 2025-02-06T21:22:50Z

docs/entities/renderer.md

+            // A list of keyframes for the part.
+            "keyframes": [
+                {
+                    // The timestamp of the keyframe. Should be between 0 and the animation length.


Timestamp is also in seconds.

IchHabeHunger54 and others added 30 commits January 29, 2024 18:04

rework registries and resource location documentation

312442d

rework side documentation

aafbf1b

rework events and lifecycle documentation

a748304

fix broken links

4b2d021

fix some mistakes regarding DeferredRegister.Blocks

c49ff55

add side checks in the event handlers

242abf0

fix some of the mistakes in registries.md

a4971bd

remove mention of registry int id syncing (it is discouraged)

9950d51

Merge remote-tracking branch 'upstream/main'

f64b8fe

update datapack registry datagen

a1bd87d

registry querying

31b5bf2

add back int ID syncing, with a big disclaimer

ff5d5b1

update sync disclaimer

965be16

address most feedback by ChampionAsh

2e65131

Update docs/blocks/index.md

1ed292c

Co-authored-by: Dennis C <[email protected]>

Update docs/concepts/registries.md

e2fbc31

Co-authored-by: Dennis C <[email protected]>

implement most of XFact's feedback

40c17a9

fix datapack registry creation

7a24414

remove recommendation of separate DR and DH classes

55873a1

fix an oversight

cdf58f2

Update docs/blocks/index.md

380db40

Co-authored-by: ChampionAsh5357 <[email protected]>

BootstapContext :screm:

2a369a7

Merge remote-tracking branch 'origin/main'

b1e1966

fix two wrong mentions of Registries

b5a78bb

fix exception name

b6dcbb9

Merge remote-tracking branch 'upstream/main'

8d54466

Merge remote-tracking branch 'upstream/main'

90c3b4a

Merge remote-tracking branch 'refs/remotes/upstream/main'

1d17916

add Champ's previous work on entities

99dd0e6

Merge remote-tracking branch 'origin/main'

a9b38d5

address luke's comment

887ed98

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) December 2, 2024 16:15 Active

XFactHD requested changes Dec 14, 2024

View reviewed changes

address xfact's comments

8e8774d

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) December 14, 2024 17:12 Active

dphaldes reviewed Dec 14, 2024

View reviewed changes

docs/entities/index.md Outdated Show resolved Hide resolved

XFactHD reviewed Dec 15, 2024

View reviewed changes

docs/entities/data.md Outdated Show resolved Hide resolved

ChampionAsh5357 requested changes Jan 10, 2025

View reviewed changes

neoforged-automation bot added the needs rebase This Pull Request needs to be rebased before being merged label Jan 10, 2025

IchHabeHunger54 added 3 commits January 11, 2025 00:19

address champ's comments, pt 1

77247ba

Merge remote-tracking branch 'origin/main'

fbc75e4

Merge branch 'main' into feature/entities

bf4efbe

# Conflicts: # docs/resources/client/models/bakedmodel.md # docs/resources/server/conditions.md

neoforged-automation bot removed the needs rebase This Pull Request needs to be rebased before being merged label Jan 10, 2025

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) January 10, 2025 23:31 Active

ChampionAsh5357 mentioned this pull request Jan 17, 2025

Add Information on Armor Overrides in IClientExtensions #186

Open

we are so back

6dc07d5

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) February 4, 2025 12:52 Active

IchHabeHunger54 added 2 commits February 6, 2025 13:59

update renderer.md

aa35a02

entity animations

2948e60

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) February 6, 2025 13:49 Active

render state modifications

97bb02e

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) February 6, 2025 15:27 Active

IchHabeHunger54 added 3 commits February 6, 2025 17:13

add spawn example

a6eb49c

fix some small oversights

71106de

mention TypeTokens for render state modifications

5db64db

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) February 6, 2025 16:22 Active

type tokens need to be anonymous classes (I love generics)

8a0900f

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) February 6, 2025 16:44 Active

ChampionAsh5357 requested changes Feb 6, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Entity docs #171

Entity docs #171

IchHabeHunger54 commented Oct 3, 2024 •

edited

Loading

XFactHD left a comment

XFactHD Dec 14, 2024

IchHabeHunger54 Dec 14, 2024

ChampionAsh5357 left a comment

ChampionAsh5357 Jan 10, 2025

IchHabeHunger54 Jan 10, 2025

ChampionAsh5357 Jan 10, 2025

neoforged-automation bot commented Jan 10, 2025

ChampionAsh5357 left a comment

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

ChampionAsh5357 Feb 6, 2025

		EntityRenderer-->ArrowRenderer;
		EntityRenderer-->LivingEntityRenderer;

		Natural spawning is performed every tick for entities where `MobCategory#isFriendly()` is true, and every 400 ticks (\= 20 seconds) for entities where `MobCategory#isFriendly()` is false. If `MobCategory#isPersistent()` returns true, this process additionally also happens on chunk generation.

		For each chunk and mob category, it is checked whether there are less than `MobCategory#getMaxInstancesPerChunk() * loadedChunks / 289` in the world. Additionally, for each chunk, it is required that there are less than `MobCategory#getMaxInstancesPerChunk()` entities of that `MobCategory` near at least one player (near means that the distance between mob and player \<\= 128) for spawning of that `MobCategory` to occur.

		if (player.hasEffect(MobEffects.DIG_SPEED)) { destroySpeed *= ...; }
		if (player.hasEffect(MobEffects.CONDUIT_POWER)) { destroySpeed *= ...; }


		## Animations

		NeoForge adds an optional system that allows entity animations to be defined in JSON files, similar to third-party libraries such as [GeckoLib][geckolib]. Animations are defined in JSON files located at `assets/<namespace>/neoforge/animations/entity/<path>.json` (so for the [resource location][rl] `examplemod:example`, the file would be located at `assets/examplemod/neoforge/animations/entity/example.json`). The format of an animation file is as follows:

Entity docs #171

Are you sure you want to change the base?

Entity docs #171

Conversation

IchHabeHunger54 commented Oct 3, 2024 • edited Loading

XFactHD left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ChampionAsh5357 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neoforged-automation bot commented Jan 10, 2025

ChampionAsh5357 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

IchHabeHunger54 commented Oct 3, 2024 •

edited

Loading